/**
 * Copyright 2006 gworks.com.au
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. (http://www.apache.org/licenses/LICENSE-2.0)
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed 
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for 
 * the specific language governing permissions and limitations under the License.
 *
 * <dhamma-message src="Atisha (11th century Tibetan Buddhist master)">
 * 	The greatest achievement is selflessness. The greatest worth is self-mastery.
 * 	The greatest quality is seeking to serve others. The greatest precept is continual awareness.
 * 	The greatest medicine is the emptiness of everything. The greatest action is not conforming with the worlds ways.
 * 	The greatest magic is transmuting the passions. The greatest generosity is non-attachment.
 * 	The greatest goodness is a peaceful mind. The greatest patience is humility.
 * 	The greatest effort is not concerned with results. The greatest meditation is a mind that lets go.
 * 	The greatest wisdom is seeing through appearances. 
 * </dhamma-message>
 */
/* Licence:
*   Use this however/wherever you like, just don't blame me if it breaks anything.
*
* Credit:
*   If you're nice, you'll leave this bit:
*
*   Class by Pierre-Alexandre Losson -- http://www.telio.be/blog
*   email : plosson@users.sourceforge.net
*/
package org.javaongems.runtime.fileupload;

import org.apache.commons.fileupload.FileItem;

/**
 * <p>Provides a monitorable output stream listener specification to enable 
 * external agents to monitor the progress of bytes being written as they are
 * being parsed from the http servlet request. This interface will get called
 * in order (ie. onStart, onBytesRead & onDone) for each uploaded file that
 * was part of the multi-part form post.</p>
 * <p>Responsiblities:
 * <ul>
 * 	<li> declare an event that will be called when a new uploaded file is  
 * 		received/parsed by commons file upload.
 * 	<li> declare an event that will be called for the number of bytes read
 * 		in any given chunk.
 * 	<li> declare an event that will be called when the file has been 
 * 		uploaded and placed in commons file upload's repository location
 * 		/memory (depending on threshold).
 * </ul>
 * </p>
 * <p>Notes:
 * <ul>
 * 	<li> changed Pierre's listener interface
 * 	<li> if you are trying to report overall progress, then the total payload  
 * 		size can be determined by querying 
 * 		HttpServletRequest::getContentLength()
 * 	<li> if you are trying to report progress of the current file, then the 
 * 		total size of the current file is reported in FileItem:getSize()
 * 	<li> if you are trying to report the name of the current file being 
 * 		uploaded then use FileItem::getName().
 * </ul>
 * </p>
 * @author Pierre-Alexandre Losson, some hacks by Ashin Wimalajeewa (ash)
 */
public interface MonitoredOutputStreamListener {
    public void onStart(FileItem item);
    public void onBytesRead(int bytesRead);
    public void onDone();
}
